Summary

This is the root cause behind the broken navigation that #457/#458/#462 have been chasing/band-aiding: client-side next/link navigation silently fails app-wide (links render but router.push no-ops), so only full-page-load <a> works.

VerificationModeProvider — added in #450 and wrapping the entire app in layout.tsx — read localStorage inside its useState initializer:

const [mode, setMode] = useState<VerificationMode>(getInitialMode); // reads localStorage

So when a user had toggled technical mode, the first client render (technical) diverged from the server HTML (normal). On a React hydration mismatch the server DOM is discarded and the tree is regenerated on the client, which breaks App Router client navigation everywhere.

This is the exact bug class #457 fixed for the store and InviteCodeBanner — it just missed this provider (also from #450). #458 then worked around the symptom by switching the sidebar to native <a>.

Fix

Make the first render deterministic (matches the server), then load the persisted preference in an effect — the same pattern as #457:

const [mode, setMode] = useState<VerificationMode>("normal");
useEffect(() => {
  const stored = localStorage.getItem(STORAGE_KEY);
  if (stored === "technical" || stored === "normal") setMode(stored);
}, []);

Adds verification-mode.test.tsx pinning the contract: first render is normal even when localStorage says technical, the persisted value applies after mount, and toggle persists.

Scope / verification note

• I swept every localStorage/window/Date/random read in the global render path (layout → AppShell and the providers it mounts). After this change, VerificationModeProvider was the only remaining render-time localStorage read; ThemeProvider, the store (fix(console-ui): sidebar nav unclickable — fix React #418 hydration mismatch #457), and InviteCodeBanner (fix(console-ui): sidebar nav unclickable — fix React #418 hydration mismatch #457) are already effect-based. ProviderSlackPopup also reads localStorage in its initializers but is masked-safe (its !isProvider gate makes the first render null on both server and client) — a latent instance of the same pattern worth hardening separately.
• Could not run a browser repro here, so I kept the native-<a> band-aids in place. Please verify on the preview deploy with localStorage['darkbloom-verification-mode'] = 'technical' that next/link navigation works (no hydration error in console).

Follow-up (separate PR)

Once verified, the native-<a> workarounds can be reverted to restore SPA navigation: the sidebar (#458) and the provider tabs (#462 — keep its "hide tabs until installed" change, revert only the <a> swap), plus the 2 remaining <Link>s in stats/earn stay correct either way.

Test plan

• npx vitest run — 3/3 in the new suite.
• npx eslint — clean.
• npm run build — succeeds.
• Manual on preview: with technical mode set, no React hydration error on load; clicking next/link elements navigates.

Made with Cursor

^{Need help on this PR? Tag /codesmith with what you need. Autofix is disabled.}